#ifndef RING_QUEUE_H
#define RING_QUEUE_H

#include <stdlib.h>

#ifdef __cplusplus
extern "C" {
#endif

struct rqueue;

typedef struct rqueue rqueue_t;

/*
 * 获得错误描述
 * @param err 接口返回的错误值
 * @return 错误描述
 */
char *rqueue_strerror(int err);

/*
 * 初始化
 * @param max_elem 最大容纳元素数量
 * @return 成功返回队列句柄，错误返回NULL
 */
rqueue_t *rqueue_init(size_t max_elem);

/*
 * 放入队列
 * @param rq 队列句柄
 * @param data 待放入的数据
 * @param max_wait_millisec 最大等待时长
 *        > 0 无法put时，最多等待时长;
 *        0   无法put时，立即返回;
 *        < 0 无法put时，永远等待;
 * @return 错误码 0表示成功，其他值为错误，可通过rqueue_strerror()接口获取错误描述
 * @note 线程安全
 */
int rqueue_put(rqueue_t *rq, const void *data, int max_wait_millisec);

/*
 * 放入队列(非阻塞模式)
 * @param  rq 队列句柄
 * @param data 待放入的数据
 * @return 错误码 0表示成功，其他值为错误，可通过rqueue_strerror()接口获取错误描述
 */
int rqueue_try_put(rqueue_t *rq, const void *data);

/*
 * 从队列取出
 * @param rq 队列句柄
 * @param pdata 指向返回数据的指针
 * @param max_wait_millisec 最大等待时长
 *        > 0 无法get时，最多等待时长;
 *        0   无法get时，立即返回;
 *        < 0 无法get时，永远等待;
 * @return 返回数据，失败为NULL
 * @note 线程安全
 */
void *rqueue_get(rqueue_t *rq, int max_wait_millisec);

/*
 * 从队列读(非阻塞模式)
 * @param  rq 队列句柄
 * @return 返回数据，失败为NULL
 */
void *rqueue_try_get(rqueue_t *rq);

/*
 * 销毁队列
 * @param rq 队列句柄
 * @param free_elem 销毁时，是否动态释放元素; 放入元素来自栈空间时，设为0
 * @return 无
 */
void rqueue_destroy(rqueue_t **rq, int free_elem);

int rqueue_size(rqueue_t *rq);

#ifdef __cplusplus
}
#endif


#endif
